---
layout: docs
page_title: 'nomad job plan command reference'
description: |
  The `nomad job plan` command executes a dry run of a job to determine its effects.
---

# `nomad job plan` command reference

**Alias: `nomad plan`**

The `job plan` command can be used to invoke the scheduler in a dry-run mode
with new jobs or when updating existing jobs to determine what would happen if
the job is submitted. Job files must conform to the [job specification] format.

## Usage

```plaintext
nomad job plan [options] <path>
```

The `job plan` command requires a single argument, specifying the path to a file
containing an HCL [job specification]. This file will be read and the resulting
parsed job will be validated. If the supplied path is "-", the job file is read
from STDIN. Otherwise it is read from the file at the supplied path or
downloaded and read from URL specified. Nomad downloads the job file using
[`go-getter`] and supports `go-getter` syntax.

Plan invokes a dry-run of the scheduler to determine the effects of submitting
either a new or updated version of a job. The plan will not result in any
changes to the cluster but gives insight into whether the job could be run
successfully and how it would affect existing allocations.

A job modify index is returned with the plan. This value can be used when
submitting the job using [`nomad job run -check-index`], which will check that
the job was not modified between the plan and run command before invoking the
scheduler. This ensures the job has not been modified since the plan.

A structured diff between the local and remote job is displayed to
give insight into what the scheduler will attempt to do and why.

If the job has specified the region, the `-region` flag and `NOMAD_REGION`
environment variable are overridden and the job's region is used.

Plan will return one of the following exit codes:

- 0: No allocations created or destroyed.
- 1: Allocations created or destroyed.
- 255: Error determining plan results.

When ACLs are enabled, this command requires a token with the `submit-job`
capability for the job's namespace.

## Options

- `-diff`: Determines whether the diff between the remote job and planned job is
  shown. Defaults to true.

- `-policy-override`: Sets the flag to force override any soft mandatory
  Sentinel policies.

- `-json`: Parses the job file as JSON. If the outer object has a Job field,
  such as from "nomad job inspect" or "nomad run -output", the value of the
  field is used as the job.

- `-hcl2-strict`: Whether an error should be produced from the HCL2 parser where
  a variable has been supplied which is not defined within the root variables.
  Defaults to true.

- `-vault-namespace`: If set, the passed Vault namespace is stored in the job
  before sending to the Nomad servers.

- `-var=<key=value>`: Variable for template, can be used multiple times.

- `-var-file=<path>`: Path to HCL2 file containing user variables.

- `-verbose`: Increase diff verbosity.

## Examples

Plan a new job that has not been previously submitted:

```shell-session
$ nomad job plan example.nomad.hcl
+ Job: "example"
+ Task Group: "cache" (1 create)
  + Task: "redis" (forces create)

Scheduler dry-run:
- All tasks successfully allocated.

Job Modify Index: 0
To submit the job with version verification run:

nomad job run -check-index 0 example.nomad.hcl

When running the job with the check-index flag, the job will only be run if the
job modify index given matches the server-side version. If the index has
changed, another user has modified the job and the plan's results are
potentially invalid.
```

Increase the count of an existing without sufficient cluster capacity:

```shell-session
$ nomad job plan example.nomad.hcl
+/- Job: "example"
+/- Task Group: "cache" (7 create, 1 in-place update)
  +/- Count: "1" => "8" (forces create)
      Task: "redis"

Scheduler dry-run:
- WARNING: Failed to place all allocations.
  Task Group "cache" (failed to place 3 allocations):
    * Resources exhausted on 1 nodes
    * Dimension "cpu" exhausted on 1 nodes

Job Modify Index: 15
To submit the job with version verification run:

nomad job run -check-index 15 example.nomad.hcl

When running the job with the check-index flag, the job will only be run if the
job modify index given matches the server-side version. If the index has
changed, another user has modified the job and the plan's results are
potentially invalid.
```

Update an existing job such that it would cause a rolling update:

```shell-session
$ nomad job plan example.nomad.hcl
+/- Job: "example"
+/- Task Group: "cache" (3 create/destroy update)
  +/- Task: "redis" (forces create/destroy update)
    +/- Config {
      +/- image:           "redis:2.8" => "redis:7"
          port_map[0][db]: "6379"
    }

Scheduler dry-run:
- All tasks successfully allocated.
- Rolling update, next evaluation will be in 10s.

Job Modify Index: 7
To submit the job with version verification run:

nomad job run -check-index 7 example.nomad.hcl

When running the job with the check-index flag, the job will only be run if the
job modify index given matches the server-side version. If the index has
changed, another user has modified the job and the plan's results are
potentially invalid.
```

Add a task to the task group using verbose mode:

```shell-session
$ nomad job plan -verbose example.nomad.hcl
+/- Job: "example"
+/- Task Group: "cache" (3 create/destroy update)
  + Task: "my-website" (forces create/destroy update)
    + Driver:      "docker"
    + KillTimeout: "5000000000"
    + Config {
      + image:            "node:6.2"
      + port_map[0][web]: "80"
    }
    + Resources {
      + CPU:      "500"
      + DiskMB:   "300"
      + MemoryMB: "256"
      + Network {
        + MBits: "10"
        + Dynamic Port {
          + Label: "web"
        }
      }
    }
    + LogConfig {
      + MaxFileSizeMB: "10"
      + MaxFiles:      "10"
    }
    + Service {
      + Name:      "website"
      + PortLabel: "web"
      + Check {
          Command:  ""
        + Interval: "10000000000"
        + Name:     "alive"
          Path:     ""
          Protocol: ""
        + Timeout:  "2000000000"
        + Type:     "tcp"
      }
    }
    Task: "redis"

Scheduler dry-run:
- All tasks successfully allocated.
- Rolling update, next evaluation will be in 10s.

Job Modify Index: 7
To submit the job with version verification run:

nomad job run -check-index 7 example.nomad.hcl

When running the job with the check-index flag, the job will only be run if the
job modify index given matches the server-side version. If the index has
changed, another user has modified the job and the plan's results are
potentially invalid.
```

When using the `nomad job plan` command in automated environments, such as
in CI/CD pipelines, it is useful to output the plan result for manual
validation and also store the check index on disk so it can be used later to
guarantee that a job deployment will match the expected changes described in
the plan result.

This can be done by parsing the command output and redirecting the index to a
file. For example, in Linux environments the [`tee`] command can be used for
this purpose:

```console
$ nomad job plan -no-color example.nomad.hcl | tee /dev/stderr | grep 'Job Modify Index:' | awk -F': ' '{ print $2 }' > check-index || true
```

The [`-no-color`](#no-color) flag prevents style characters from impacting
parsing. Colored output may be helpful when analyzing the plan result, so the
[`-force-color`](#force-color) flag can be used. This will affect how parsing
is done to avoid hidden control characters. Adding `|| true` at the end
prevents undesired failures since `nomad job plan` returns a non-zero exit code
if a change is detected.

## General options

@include 'general_options.mdx'

[job specification]: /nomad/docs/job-specification
[hcl job specification]: /nomad/docs/job-specification
[`go-getter`]: https://github.com/hashicorp/go-getter
[`nomad job run -check-index`]: /nomad/commands/job/run#check-index
[`tee`]: https://man7.org/linux/man-pages/man1/tee.1.html
